# 三种策略基类：RuleIterator、FactorSorter、GeneralStg

qteasy 中自定义策略通常继承自三种基类之一，按使用场景选择：**RuleIterator** 适用于择时或单规则迭代；**FactorSorter** 适用于因子选股；**GeneralStg** 适用于通用多资产或多规则信号。

## 何时用哪种基类

- **RuleIterator**：单标的或单规则、逐周期迭代（如均线择时、MACD 择时）。输入多为单标的或多标的的行情序列，输出为仓位或单一信号。
- **FactorSorter**：多标的按某一因子排序，选取前 N 或后 N 名（选股）。需设置 **max_sel_count**、**sort_ascending** 等。
- **GeneralStg**：更通用的多资产、多规则或自定义输入输出形状的策略，当 RuleIterator/FactorSorter 无法满足时使用。

## RuleIterator

- **输入/输出**：通常通过 ``get_data(dtype_id)`` 获取 OHLCV 等，在 ``realize()`` 中计算并返回一维信号（如目标仓位 0～1）。
- **典型用法**：均线金叉死叉、MACD 柱状图符号等。
- 简短示例（逻辑示意）：

```python
from qteasy import RuleIterator, Parameter

class MyTiming(RuleIterator):
    def __init__(self):
        super().__init__(pars=[Parameter('period', 20)], ...)
    def realize(self):
        close = self.get_data('close')
        # 简单均线规则
        return (close[-1] > close[-self.get_pars()['period']:].mean()).astype(float)
```

### 多标的参数（必读）

- **需要每股不同参数时**：必须在 ``set_shares`` / ``Operator.set_shares`` 之后，用 **字典** 调用 ``update_par_values({代码: (参数元组), ...})``（或通过 ``Operator.set_parameter(..., par_values={...})`` 等效传入）。字典的键须与当前标的列表中的字符串 **完全一致**。框架据此建立按标的顺序排列的 per-share 参数；之后在 ``realize()`` 里用 ``get_pars()`` / ``update_par_values()`` 即可，由框架在 ``generate()`` 循环内对齐当前股票。
- **若用元组 / 位置参数初始化**：多标的时运行时 **全体共享一套** 策略参数（单一 ``_pars``）。若本意是「每只股票独立一套参数」却未传字典，易产生静默语义偏差；**刻意让所有股票共用一套初值并一起演化** 时，用元组是合理选择。
- **``default`` 键（不是 ``others``）**：字典中除具体股票代码外，可额外提供键 ``"default"``，其值为一个参数元组；凡 **未在字典中单独列出** 的标的，初始化时都会使用该元组作为初值。之后各标的在回测/实盘中的参数仍可在 ``realize()`` 内通过 ``update_par_values`` 独立演进。实现上 **没有** ``others``、``rest`` 等其它魔法键名，请勿使用未文档化的键。

## FactorSorter

- **输入/输出**：获取因子数据（如收益率、波动率），在 ``realize()`` 中返回每个标的的因子值；基类按 **sort_ascending** 排序后取前 **max_sel_count** 个形成选股列表。
- **属性**：max_sel_count（选股数量）、sort_ascending（True 升序取最小，False 降序取最大）等。

## GeneralStg

- **输入/输出**：更灵活，可自定义所需 DataType 与返回数组形状，适用于多资产权重、多规则组合等。
- **适用场景**：不限于单标的择时或简单因子选股时的自定义逻辑。